Word Solution Engine (WS) is an object code module which can be included in a Macintosh application to provide a developer with text editing far superior to the existing Macintosh tools.
Using the object code along with this Programmer's Guide, WS literally becomes an extension to the Mac Toolbox.
Getting Started
Word Solution Engine is an object-code module to be included with your application.
Regardless of what language you developing in, there are two approaches you may take for hooking into WS.
On the "WS Engine-Object" disk you received from DataPak there is a Folder called LINKABLE OBJECT and another called RES OBJECT.
The linkable object Folder contains the necessary object-code files you can directly link into your application program; the res object Folder contains the same WS object-code except it is in the form of an independent resource that loads externally to your program.
The difference between the two types of object files are simply the way they get included into your program -- both are exactly the same in all other respects.
The linkable object, at this time, is limited to MPW Pascal, MPW C, MPW Assembler, Think C, and Think Pascal.
The res object is essentially not limited to any Mac programming environment since it loads and runs independently of your compiled code.
The linkable version is mainly used for stand-alone applications while the res version is used for Desk Accessories, Hypercard externals, etc. where the code cannot depend upon the Segment Loader or register A5.
STEPS TO INCLUDE THE LINKABLE OBJECT
1. You will only need the files in the linkable object folder.
2. For PASCAL, include the "WSIntf.p" as a unit to obtain all the predefined constants, procedures and functions; for "C", include "WSInft.h" as a header file to reference all the structures and functions outlined in this manual.
3. Write your program by following the routines given in Section II and III, "Using Word Solution" and "WS Routines".
4. At link time, include the WS object code file. For MPW, use Core.Linked.a.o; for Think C, use Core.Linked.a.π and use the Core.Linked.v file for vocabulary (case definitions).
STEPS TO INCLUDE THE RES OBJECT
1. You will only need the files in the res object folder.
2. For PASCAL, include the "WSIntf.p" as a unit to obtain all the predefined constants, procedures and functions; for "C", include "WSInft.h" as a header file to reference all the structures and functions outlined in this manual.
3. Write your program by following the routines given in Section II and III, "Using Word Solution" and "WS Routines".
4. At link time, include the small object file that provides "glue" between your program and the WS "code" resource. For MPW, use "wp.ResGlue.a.o"; for Think C, use "wp.ResGlue.a.π" and use the "wp.ResGlue.a.v" file for vocabulary (case definitions).
5. If you have not done so already, install the resource 'WSXT' into your application resource file (or the System file, whichever is appropriate to your situation -- the idea is the resource must be loadable at run-time). The 'WSXT' resource can be found in the "WS.Resource" file also included in the res object folder.
Word Solution Basics
All the routines given in this manual work exactly the same as those found in Inside Macintosh.
If you have included the object code and interface files correctly (explained in "Getting Started," above), every WS routine is available to your application.
Depending upon your development intentions, parts of this manual may be skipped. To help in this manner, here is a brief outline of its sections:
I. Record Structures. This section explains the various record structures used by WS. If you're only going to do very basic editing, almost all of this section can be skipped.
II. Using Word Solution. This section outlines the general steps for creating an application with WS. For Mac "veterans" much of this section can be skipped.
III. WS Routines. This section documents each WS routine, broken down by various topics. There is no way, of course, you can skip this section entirely since these are the routines you will be using in your program.
IV. Advanced Techniques. This section covers the subject of customizing text display and using WS low-level hooks. If you're not planning these advance techniques, skip this section.
I. Record Structures
This section describes the data structures used by WS. It is not necesssary to know everything about these structures to effectively use Word Solution Engine. This information is provided mainly to offer programmer's wide versatility and comprehension of the internals.
Almost every Procedure and Function involve the WSHandle whose structure is as follows:
WSHandle = ^WSPtr;
WSPtr = ^WSRec;
WSRec = Record
tHandle:TextStuff; { Handle to text structures }
tLength:LongInt; { Total length of text }
tRect:Rect; { Display rectangle }
tBounds:LongRect; { Bounds "rectangle" }
thBase:LongInt; { Original h-scroll position }
tvBase:LongInt; { Original v-scroll position }
tBegin:tSelectPos; { Begin selection }
tEnd:tSelectPos; { End Selection }
tCalc:tSelectPos; { Next place to recalc }
tCalcEnd:tSelectPos; { Place to end recalc }
tTop:tSelectPos; { Top visible line in tRect }
tFormat:FormatHandle; { Format Run }
tFmt:FormatRec; { Current Format (of caret position) }
tJust:Integer; { Justification of text }
tFlags:LongInt; { Misc. attributes }
tArrow:Integer; { Used for arrow keys }
tRefCon:LongInt; { For application use }
tProcs:WSHooksPtr; { Hooks for a variety of stuff }
{ Remainder for use by Levels 1 and 2 }
END;
Here is a brief description for each field of the WSRec:
tHandle. Contains a specially defined handle for text structures to be edited or displayed. (The variable, TextStuff, is defined later on under "Text Buffering").
tLength. The total length of text. NOTE: This is never zero -- there are always two null (0) characters at the end of the text.
tRect. The area rectangle, in local coordinates, where the text structure may display. It differs from tBounds (below) in that tRect merely "clips" the visual display while tBounds defines the relative text display ("scrolled" state) and the maximum width for word wrapping (see the illustration for the function, "WSNew").
tBounds. The area the text display gets pinned to, in local co-ordinates. In essence, the position of tBounds defines the visual "scrolled" position (see WSNew, below).
However, since WScan handle extremely large amounts of text, it is conceivable that tBounds could scroll past the boundaries of 32,768; thus, tBounds is defined as an expanded rectangle structure as follows:
LongRect = RECORD
Top:LongInt; { "Top" side }
Left:LongInt; { "Left" side }
Bottom:LongInt; { "Bottom" side }
Right:LongInt; { "Right" side }
END;
thBase, tvBase. The original left and top edges, respectively, of tBounds. This is used by WS to maintain knowledge of where the contents are "scrolled."
tBegin, tEnd. The beginning and ending selection points, respectively. A tSelectPos is predefined as follows:
TYPE tSelectPos = RECORD
Pos:LongInt; { Offset into text }
Buffer:LongInt; { Offset into text buffer array }
Line:LongInt; { Offset into Line Array }
Caret:Integer; { "Caret" or left-edge, in pixels }
END;
The Pos value gives the absolute offset into the text; Buffer is an offset into an array of text buffers which contains Pos offset (see "Text Buffering"); Line is the absolute offset into the concatenated line arrays for each text buffer, while Caret is the pixel offset of the insertion point (of left edge of highlighted text).
For the most part, your application won't need to use any of these fields -- the information you might need is usually obtainable through various procedures and functions.
tCalc, tCalcEnd. These are tSelectPos records (defined above) which get set by various WS routines whenever text needs to be recalculated (such as changes in Font, word wrapping, etc.). Unless you are doing something unusually fancy, you generally won't need to see or change this information.
tTop. This is the first visible line within the visual rectangle. It is defined as a tSelectPos record, explained above. It is maintained internally by WS and doesn't need to be updated by your application.
tFormat. This is the format run for the entire text structure (information about Font, Style, etc.) whose predefined structure is as follows:
FormatRec = RECORD
Pos:LongInt; { Offset to text }
UserProcs:UserStylesPtr; { Pointer to User Style routines }
fReal:Integer; { Font is "real" if non-zero }
fName:String[31]; { Font Name }
fStyle:Integer; { Text style }
fPoint:Fixed; { Point size (fractional) }
fgColor:RGBColor; { Foreground color }
Txr:Integer; { Transfer mode (Color systems only) }
cExtra:Fixed; { CharExtra value (char spacing) }
Leading:Integer; { +- offset for baseline }
UserSpace:LongInt; { Space provided for UserStyles }
END;
FormatPtr = ^FormatRec;
FormatHandle = ^FormatPtr;
FormatAPtr = ^FormatArray;
FormatArray = ARRAY[0..0] OF FormatRec;
Field Pos contains the absolute offset into text where this format record begins.
UserProcs is a pointer to low-level routines which an application can hook into to create custom styles and specialized displays. UserProcs contains either NIL (which means WS will handle text stylations itself) or a pointer to a predefined structure, UserStyles. SEE "LOW-LEVEL HOOK ROUTINES" AND "USER STYLES" IN THE LAST SECTION OF THIS MANUAL FOR MORE INFORMATION.
Field fReal is non-zero if the combination font and point size is a "real" font (not scaled).
Field fName is the name of the font used for this format run. WS uses font names (as opposed to integers) to be compatible with all future systems.
Field fStyle is the textface value for the text, represented by the following bits:
Bits 0-7 Standard Quickdraw style bits
Bit 8-15 ** reserved for future enhancement **
Field fPoint is a fixed point variable defining the point size. Note that fractional point sizes can be recorded and retrieved for each style run; however, the current version of WS only looks at the high-order word of fStyle (whole integer) but a fixed variable has been given for future enhancement.
Field fgColor is an RGBColor defining the foreground color of the text. This will only have effect in a Color Quickdraw environment.
Field Txr is taken as the text transfer mode. However, the current version of WS does not use this field and is reserved for future enhancement.
Field cExtra is a fixed point variable used to extend or condense characters ("CharExtra") and allow for variable character spacing (for kerning features, etc.). However, the current version of WS does not use this field and is reserved for future enhancement.
Leading is reserved for future "add-on" style enhancements.
UserSpace is provided for the application using User Styles. This space will never be changed by WS and can be used for any purpose by the application.
tFmt. This field contains the current format record of the insertion point (or the overall format for the selection range). The record structure is a FormatRec defined above.
tJust. This defines the overall justification of the text structure as follows:
0 -- Left Justify
1 -- Center Justify
2 -- Right Justify
3 -- Full Justify
For WS, there is only one field for justification (affecting all text).
tFlags. This contains 32 bits of information for specific attributes of the text.
At this time, tFlags contain the following possible attributes:
CONST NoWrap = 1; { If set, no text wrapping }
CaretOn = 2; { Caret is currently displaying }
NeedsCalc = 4; { Text needs recalculating }
Deactive = 8; { Inactive state }
ViewOnly = 16; { No editing -- view-only }
{ Other bits reserved for future enhancement }
tArrow. This is used internally for up and down arrow key control.
tRefCon. This long integer space can be used for anything by the application.
tProcs. This contains a pointer to an array of low-level WS routines that the application may hook into for specialized features. The format and description for each low-level routine is described in detail under "Low-Level Hook Routines" in the last section of this manual.
Text Buffering
In order to handle very large blocks of text at optimum speed, WS breaks the text stream into individual text buffers. This also provides easy enhancement for disk buffering, etc. An individual text buffer is predefined as follows:
TextBlock = RECORD
TBBegin:LongInt; { Absolute text beginning }
TBEnd:LongInt; { Absolute text end }
TBLines:LineHandle; { Line array }
TBLineBeg:LongInt; { Absolute line beginning }
TBLineEnd:LongInt; { Absolute line ending }
TBPixBeg:LongInt; { Pixel height beginning }
TBPixEnd:LongInt; { Pixel height ending }
TBFlags:LongInt; { Misc. attributes }
TBHandle:CharsHandle; { Actual text }
TBCTL:Handle; { Control Char Run }
TBLev1:LongInt; { Reserved for future }
TBLev2:LongInt; { Reserved for future }
END;
Most of the fields in the text block record will only be used internally by WS. However, here is a brief description for some of the important fields:
TBBegin, TBEnd. The absolute beginning and ending of text, respectively, as if all text buffers were contiguous.
TBLines. Contains the line array of the text in this block. The line array is described in detail later on.
TBLineBeg, TBLineEnd. The beginning and ending offsets of the line array relative to the entire WS structure.
TBPixBeg, TBPixEnd. The pixel position of the beginning and ending lines relative to the entire WS structure.
TBHandle. The text itself for this block. If this is the last (ending) text block, the text contains two NUL (0) characters as a terminator.
All other fields are used internally by WS and should never be altered by the application.
Text blocks are maintained by WS as an array of handles:
TextStuff = ^TextArrayPtr;
TextArrayPtr = ^TextArray;
TextArray = ARRAY[0..0] OF TextBlock;
The Line Array
WS maintains an array of records defining line and word breaks for each text buffer.
A line array entry is predefined as follows:
LineRec = RECORD
Pos:LongInt; { Offset into text where line begins }
Length:Integer; { Length of line }
Top:LongInt; { Relative top of line }
Height:Integer; { The line's total height, in pixels }
Left:Integer; { Amount to offset for line drawing }
Base:Integer; { Vertical baseline to draw text }
Flags:Integer; { Reserved for internal use }
rNum:Integer; { Reserved for internal use }
Width:Integer; { The line's total width, in pixels }
DLength:Integer; { Displayable length }
END;
The Pos field contains the relative position into the text. This position is relative to all text, not the text buffer that "owns" this line.
Length contains the total length of the line.
Top is the relative vertical pixel position used for display and selection purposes. It is always relative to the tBounds field of WS -- it is not an absolute screen position. The line's horizontal position is always assumed to be zero (relative to tBounds left position).
Height is the line's total height, in pixels.
Left is an optional distance to offset the line for drawing and mouse-clicks. Note, however, that this is always zero by default unless the application (or future enhancement) alters it directly.
Base is the vertical distance from the line's bottom edge to commence drawing (baseline).
Flags and rNum are used internally by WS and must never be altered.
Width contains the total width of the line, in pixels.
DLength is the lines displayable length. This might be different than the Length field, for instance, on a line that ends with a RETURN character.
Line arrays are maintained and grow dynamically using the following predefined structure:
LineHandle = ^LineAPtr;
LineAPtr = ^LineArray;
LineArray = ARRAY[0..0] OF LineRec;
Global Parameters
WS maintains a few global parameters (applied to all WSHandles) via the following predefined format:
WSGlobalsPtr = ^WSGlobals;
WSGlobals = RECORD
Version:LongInt; { WS Software Version }
MaxBufSize:LongInt; { Maximum buffer size }
Extension:ProcPtr; { Called for extension modules }
Script:LongInt; { System + Application Script }
QDBits:GrafPort; { Offscreen bitmap port }
QDPix:cGrafPort; { Offscreen color pixmap port }
PortBuf:Handle; { Bits used for offscreen mapping }
TabSpace:Integer; { Default TAB spacing }
Decimal:Integer; { Decimal char }
Return:Integer; { RETURN char }
LF:Integer; { Line Feed char }
Tab:Integer; { TAB char }
Backspace:Integer; { Backspace char }
Hyphen:Integer; { Hyphenation char }
END;
Version. Contains the running version of WS.
MaxBufSize -- The maximum buffer size for a text block (see TextStuff format). The default value on start-up = 1536.
Extension -- A procedure pointer called by WS for special add-on extensions. The application shouldn't alter this field.
Script -- This field is non-zero if anything besides Roman script is being used. An example of non-Roman script would be Kanji (Japanese) Script.
QDBits, QDPix -- A GrafPort and cGrafPort to be used for offscreen drawing. Only Color Quickdraw environments will have QDPix.
PortBuf -- Contains bitmap memory for black and white bitmap drawing.
TabSpace -- The default tab stop value when there are no tab stops. The default value is 24 pixels).
Decimal -- Reserved for future enhancement.
Return through Hyphen -- Contain the characters to be used for RETURN, LINEFEED, TAB, BACKSPACE, and HYPHEN (hyphenation), respectively.
Through various procedures and functions, the application can change the values for each of the fields above.
II. Using Word Solution Engine
This section has been provided to give you a general understanding and overview for using Word Solution -- a more thorough description of each routine is given in the next section, WS Routines.
All of this section assumes you have a basic understanding of Inside Macintosh and Mac programming in general.
Initialization
Before any WS routine can be accessed, you must call WSStartup -- this initializes all the global variables and internal memory structures of WS (as well as load the "code" resource if you are using the stand-alone resource object). If you're concerned about low-memory errors you need to pass a pointer to an error function at this time.
Then, to create an "empty" editing structure call WSNew and pass all the appropriate parameters to create the desired result. The WSNew function returns a WSHandle which you will pass to almost every other function.
From this point you need to repeatedly call WSIdle to make the "caret" toggle for that particular WSHandle; typically, WSIdle is called once during every GetNextEvent loop.
NOTE: Never at any time does WS "attach" itself to any particular window or GrafPort; all display and editing operations occur on the current GrafPort -- WS doesn't not "remember" what window was selected when you created a WSHandle.
Once you are completely through using a WSHandle, call WSDispose.
Response to Events
The way you respond to Events is very similar to TextEdit:
For KeyEvents, call WSKey.
For MouseDown events, call WSClick. If you want to automatically scroll when the mouse drags through text, pass a pointer to such a procedure in the IdleProc parameter of WSClick.
For Activate events, determine whether it is a deactivate of activate event and call WSActivate or WSDeactivate, whichever applies.
For Update events, call WSDisplay. Note that for this event, be sure to pass TRUE for displaying the selection range, otherwise the WSHandle might not visually update properly.
For scrolling in general, simply call WSScroll and WS updates the scrolled areas appropriately.
For a simple "test" program, the above is all you need to do to obtain the basics of text editing.
Changing Text Format
WS maintains multiple stylations, that is, different characters can be any standard font, text face, and/or point size.
If a change is made to the text format while there is only an insertion point ("caret"), the change only occurs on the next WSKey; if a change is made while text is selected (highlighted), the change occurs immediately.
NOTE: If text formatting changes immediately (becuase text is highlighted), it does not automatically re-display -- you need to call WSDisplay for the effect to be seen.
To change the font, call WSSetFont.
To change the text face ("style"), call WSSetStyle.
To change the point size, call WSSetPoint.
To change the color (32-bit color), call WSSetColor.
To change text justification, call WSSetJust. Note, however, that WS does not support unique justifications for individual paragraphs -- the justification affects all text.
You can get information from a WSHandle as to which font, style, point size or color the selection range contains by calling WSGetFont, WSGetStyle, WSGetPoint and WSGetColor, respectively. You can get the justification by calling WSGetJust.
Cut, Copy, Paste, and Undo
WS provides a minimal set of routines to manipulate the "scrap."
If so desired, you can transform the external scrap to a WSHandle by calling WSScrapToHandle.
To delete selected text ("Cut" or "Clear"), call WSCut.
To copy a selected range, call WSCopy.
To "paste" text, call WSPaste to insert the results of a previous WSCopy.
Note that to perform a true "Cut" operation, you should first call WSCopy (causing the selected contents to transfer to the scrap) then WSCut to delete the text.
Although WS does not support an "Undo" as such, an Undo operation can be accomplished by using a combination of WSCut, WSCopy, and WSPaste.
You can perform a "format change" undo by using WSCopyFormat and WSApplyFormat.
You can draw a "clipboard" by merely displaying the results of WSCopy.
When your application quits, you can force WS's internal scrap into the Mac's external scrap by calling WSToScrap.
Inserting Raw Text
WS provides several routines to transfer raw text to and from a WSHandle.
The easiest way is through WSSetText which replaces all text with the contents passed to it.
A more sophisticated way is to call WSText2New (which creates a new WSHandle from a block of text and a predefined format) then do a WSPaste using that handle. This creates a raw text "insertion" and also allows you to control the particular text format of the insertion.
To obtain raw text from a WSHandle, call WSGetText to get all text or WSGetSelText to obtain only the selected (highlighted) text.
I/O & Printing Support
WS provides to routines to aid the saving and retrieving of WSHandles (to a file, for instance). These are WSToHandle and HandleToWS, which converts a WSHandle to a single, contiguous data structure, or reverses the process, respectively.
For printing, use WSPrint (rather than WSDisplay) to obtain optimum results. WSPrint also allows you to control where text is drawn on the page regardless of its currently scrolled position.
Customizing Text & Advance Techniques
Once you are thoroughly fimiliar with the basics of WS and wish to customize display and editing (such as graphic pictures or additional styles), refer to the last section of this manual, "Advance Techniques".
Ending Off
Before your application quits, call WSShutDown. Note, however, that once WSShutDown is called you can no longer access any WS routine until you call WSStartup.
Initializes WS, allocating the code resource and allocates internal memory.
ResID is the resource number for a WSXT resource (Word Solution External) if you are using the stand-alone "code" resource method; otherwise, ResID is ignored. The default ResId = 128.
ErrorProc is an optional pointer to a function that is called if WS runs out of memory. It is taken in the form of:
FUNCTION MyErrorProc (cbNeeded:LongInt):Boolean;
The cbNeeded parameter contains the amount of memory that WS is short (this value is taken from the GrowZone procedure outlined in the Memory Manager). If the function returns TRUE, then WS retries for memory allocation; if it fails again, the error procedure is called. This process is repeated until either memory is successfully allocated or the function returns FALSE.
If the ErrorProc returns FALSE, WS will gracefully back out of whatever it was doing (which includes disposing all memory that it had temporarily created during the current action) and return control to the application. An example where this might occur is a massive WSPaste call that runs out of memory half way through the "paste" process -- once the application tells WS to give up via the error procedure, WS would dispose the half-way paste and return from the WSPaste function.
Note: If you provide an error procedure, WS calls SetGrowZone to intercept tight memory situations; if you are calling SetGrowZone as well it will never get to the WS error procedure.
Besides out-of-memory, there is one other error that gets reported:
-1 Buffer too large with no RETURN of LF.
If cbNeeded returns -1, too much text exists in a text buffer and has no RETURN of LINE FEED characters (WS always splits buffers on a "RETURN" boundary). Under normal editing, this situation should not occur.
PROCEDURE WSShutDown;
Shuts down WS and deallocates the code resource and any other memory structure it created.
Call this procedure once you are completely through with WS.
NOTE: You don't need to call WSShutDown if your application does an ExitToShell.
PROCEDURE WSGetGlobals (VAR Globals:WSGlobals);
Returns the current WSGlobals used by WS.
PROCEDURE WSSetGlobals (Globals:WSGlobals);
Sets the current globals to the values in Globals.
Warning: WS will recognize any memory structures in Globals that you have created yourself; if so, it will deallocate its own. However, once you have called WSSetGlobals the memory structures now "belong" to WS and will be disposed by WS at the appropriate time.
FUNCTION WSColorEnable:Boolean;
Returns whether the current system supports Color Quickdraw. This function is provided for an easy way to detect a colored environment. As result of TRUE indicates color.
Please note, however, that you can still set the color values (using WSSetColor) for various ranges of text in a non-colored environment -- it just won't display the color.
PROCEDURE WSInitHooks (Hooks:WSHooksPtr);
Initalizes a WSHooks record to all NIL ProcPtrs. The Hooks parameter points to a WSHooks record.
WSInitHooks is provided for an easy way to force the ProcPtr's to NIL from high-level languages.
Allocating & Disposing Handles
FUNCTION WSNew (ViewRect:Rect; Bounds:LongRect; Flags:LongInt; Hooks:WSHooksPtr; Format:FormatPtr):WSHandle;
Allocates a new WSHandle.
ViewRect is the display rectangle, in local coordinates. Bounds is taken as the predefined LongRect structure to allow movement greater than 32,768 pixels.
The difference between ViewRect and Bounds is that ViewRect is the clipped "window" area where the text can be seen, while Bounds defines both the top-left "scrolled" position of the text as well as the maximum text width boundaries for word-wrapping.
Figure 2a and 2b show how ViewRect and Bounds work together: by simply moving the Bounds rectangle's location the text is visually "scrolled."
The Flags parameter sets certain attributes of the newly created WSHandle. Currently there are three predefined bit settings for Flags:
CONST NoWrap = 1; { If set, no text wrapping }
Deactive = 8; { Inactive state }
ViewOnly = 16; { No editing -- view-only }
Hooks is an optional pointer to WSHooks (low-level routines) to be used by this WSHandle. If Hooks = NIL, the WSHandle uses the standard routines.
Format is a pointer to a format record that defines the beginning font, style, point size, and other text characteristics. If Format = NIL, the WSHandle's format defaults to the Application Font, 12 point plain text.
FUNCTION WSText2New (Text:CharsHandle; ViewRect:Rect; Bounds:LongRect; Flags:LongInt; Hooks:WSHooksPtr; Format:FormatPtr):WSHandle;
WSText2New works the same way as WSNew except it inserts Text data into the newly created WSHandle.
The parameters in addition to Text are identical to WSNew.
Note that a copy is made of Text so you need to dispose the CharsHandle sometime after this call.
WSTest2New is the same as calling WSNew and then WSSetText except WSText2New provides a way to force the inserted text to specific stylations.
PROCEDURE WSDispose (WS:WSHandle);
Disposes a WSHandle's memory structures, including the WSHandle itself.
Use WSDispose once you are completely through with a WSHandle.
Disposes all previous text of WS and replaces it with a copy of TheText.
Note that a copy is made of TheText -- you must dispose of TheText sometime after WSSetText.
Also note that the current text of WS is disposed -- if you need to insert text without disposing what is already there, other routines are provided (such as a combination of WSText2New and WSPaste).
FUNCTION WSGetText (WS:WSHandle):CharsHandle;
Returns all text within WS as one contiquous CharsHandle.
The handle returned is a copy of all the text. If such a copy cannot be returned (due to memory restrictions), NIL is returned (after the global ErrorProc is called).
Note: WSGetText does not return any style information. Use WSCopy for that purpose.
FUNCTION WSGetSelText (WS:WSHandle):CharsHandle;
Returns all text of the selection range in WS as one contiquous CharsHandle.
The handle returned is a copy of all the text. If such a copy cannot be returned (due to memory restrictions), NIL is returned (after the global ErrorProc is called).
WSGetSelText works exactly the same as WSGetText except only the selection range is returned. If there is no selection range, the CharsHandle is still returned but it will be zero length in size.
Note: WSGetSelText does not return any style information. Use WSCopy for that purpose.
Returns a TextBlock record in WS. The Position parameter as a number from 0 to number of TextBlock records-1. The wanted TextBlock is copied into TBuf.
If there is no such TextBlock (i.e., beyond range of array) then TBuf is initialized to all zeros.
FUNCTION WSFindBuf (WS:WSHandle; Contains:LongInt;
VAR TBuf:TextBlock):Integer;
Returns the TextBlock record containing the absolute offset Contains into text.
The TextBlock in WS containing the desired offset is copied into TBuf; the function returns the array number of the block (the first one is zero).
WSFindBuf always returns a text block even if Contains is beyond the range of text; therefore, passing some large arbitrary number causes the ending TextBlock record of the array to be returned.
FUNCTION WSGetNumBufs (WS:WSHandle):Integer;
Returns the number of TextBlock entries in WS. This function will never return zero if WS is a valid WSHandle.
Line Calculation & Display
FUNCTION WSRebuild (WS:WSHandle; AllBufs:Boolean):LongInt;
Recalculates as many text lines as necessary for WS to display properly.
WS was designed this way so many operations can be performed without the delay of recalculation for each major change. Hence, the application can control when and if there is a major recalculation.
Note, however, that if you end up displaying a WSHandle that requires calculation, WS is forced to recalculate prior to the display; WSRebuild is provided in case you want to control that moment yourself.
If AllBufs = TRUE, the rebuild process considers all text buffers as necessary to do a full rebuild; if FALSE, only the text buffer at the start of the required rebuilding is calculated. For speed-critical applications, the setting of TRUE may cause a major slow-down for very large blocks of text.
The function returns the offset of the first line record that needed recalculation, if any (this result can subsequently be passed to WSDisplay for maximum display speed); if nothing was recalculated, the function returns -1 (minus one).
Displays the contents of WS to the current GrafPort.
The From parameter gives the starting offset of text to be displayed. Note that this offset is obtainable from the WSRebuild function result and that a value of -1 will result in no display.
However, it is safe to pass zero in the From parameter since WS won't display anything outside of the view portion of WS.
The Erase parameter indicates whether the background is to be erased prior to display; a value of TRUE causes the view area to erase.
ShowSel causes if caret and/or highlighting to display as well if the value is TRUE.
If CaretState = TRUE, the caret is turned on if not on already; if FALSE, it is turned off if not off already.
CAUTION: Be sure to set the GrafPort where WS is normally drawn to; this routine does not set it for you.
Note: Don't use WSSetCaret for activate and deactivate events -- use WSActivate and WSDeactivate instead.
Events, Mice and Keys
PROCEDURE WSActivate (WS:WSHandle);
Causes WS to be an active WSHandle.
Use WSActivate in response to an activate event that belongs to a window containing WS.
An "active" WSHandle enables the blinking caret or the highlighted text display.
If WS is already active, this call does nothing.
CAUTION: Be sure to set the GrafPort where WS is normally drawn to; this routine does not set it for you.
PROCEDURE WSDeactivate (WS:WSHandle);
Causes WS to be an inactive WSHandle.
Use WSDeactivate in response to a deactivate event that belongs to a window containing WS.
A "deactive" WSHandle disables the blinking caret or the highlighted text display.
If WS is already inactive, this call does nothing.
CAUTION: Be sure to set the GrafPort where WS is normally drawn to; this routine does not set it for you.
PROCEDURE WSIdle (WS:WSHandle);
Causes the "caret" to blink in WS.
Use WSIdle during your "event loop" to cause the caret to toggle.
If WS has been deactivated, WSIdle does nothing.
CAUTION: Be sure to set the GrafPort where WS is normally drawn to; this routine does not set it for you.
PROCEDURE WSKey (WS:WSHandle; Ev:EventRecord);
Inserts a character in response to a KeyDown event.
Ev is the EventRecord taken exactly from the KeyDown event.
WSKey will insert the character from Ev at the current insertion point and redisplay the appropriate visual contents of tRect.
WSKey handles any situation for KeyEvent handling: RETURN, backspace, TAB, and arrow keys. Word-wrapping and re-display is performed as needed; scrolling, however, is not not.
SCRIPT MANAGER NOTE: The advise given in "Inside Mac" when using the Script Manager for non-Roman scripts of buffering keys until you have a valid character is not necessary with WS -- WSKey is handled correctly even for multi-byte characters.
FUNCTION WSInsert (WS:WSHandle; Data:Ptr; Count:Integer):Boolean;
Inserts Data of Count bytes into WS at the current insertion point.
The function returns TRUE if the text requires re-displaying.
WSInsert is mainly provided as an alternative way to insert characters if WSKey isn't used.
Changes the insertion point in WS to match the exact mouse point in response to a MouseDown event and begins tracking the mouse movements.
Ev is the EventRecord taken exactly from a MouseDown event.
The mouse is tracked repeatedly, highlighting text as necessary, until the mouse is released. During the tracking, IdleProc is repeatedly called and is taken in the following format:
NewMouse is the current mouse point, in local co-ordinates.
Note: Be sure to set the correct GrafPort prior to WSClick and before returning from IdleProc. WS never sets any GrafPort.
THE OTHER WS PROCEDURES AND FUNCTIONS CAN BE RE-ENTERED DURING THE IDLEPROC. For instance, an application would often call WSScroll to perform automatic scrolling.
If WSScroll is called during the mouse tracking, WS is "smart" enough to know this and will adjust all internal values accordingly so automatic scroll will work correctly.
Changing Text Format
NOTE: None of the formatting routines automatically re-display the text -- call WSDisplay or WSBitMapDisplay to update the screen contents.
FUNCTION WSSetFont (WS:WSHandle; FontName:STR255):Boolean;
Sets the font for WS to FontName.
If there is a selection range, than all characters selected become FontName; otherwise, the new font becomes the current font for the next WSKey.
The font parameter is taken as a name to be compatible with all future System releases.
If text needs to be redisplayed as a result of WSSetFont, this function returns TRUE.
FUNCTION WSSetPoint (WS:WSHandle; PtSize:Fixed):Boolean;
Sets the point size for WS to Point. The point size is taken as a fixed fraction to allow fractional point size for future enhancement; for the current version, set the high-order word to the point size and the low-order word to zero (or, another way, is to call FixRatio(pointSize,1) to obtain the proper "ratio").
If there is a selection range, than all characters selected become Point; otherwise, the new point size becomes the text size for the next WSKey.
If text needs to be redisplayed as a result of WSSetPoint, this function returns TRUE.
FUNCTION WSSetStyle (WS:WSHandle; TheStyle:Integer):Boolean;
Sets the text face (style) for WS to TheStyle. The style is taken as a 16-bit integer, the low-order byte is the Quickdraw style byte; the high-order byte is reserved for additional "add-on" enhancements.
The way TheStyle affects text (or the next key insert) is as follows:
If TheStyle bits are all zero ("plain"), the text is forced to plain.
If a style in TheStyle does not hold true throughout the selected range of text, the entire selection range is set for that style; if a style in TheStyle does hold true throughout, the style gets turned OFF.
If text needs to be redisplayed as a result of WSSetStyle, this function returns TRUE.
FUNCTION WSSetColor (WS:WSHandle; Color:RGBColor):Boolean;
Sets the foreground color of text for WS to Color. The color is taken as a Color Quickdraw RGBColor. Note that the color attribute gets stored in the format run even if the running environment does not support color.
If there is a selection range, than all characters selected become Color; otherwise, the new color becomes the foreground for the next WSKey.
If text needs to be redisplayed as a result of WSSetColor, this function returns TRUE. (The function will never return TRUE if the running environment does not support color -- but the information gets stored in the format array).
FUNCTION WSGetFont (WS:WSHandle; VAR FontName:STR255):Boolean;
Returns the current font in WS.
FontName is set to the name of the font used.
If there is a selection range and the same font does not hold true throughout the range, the function returns FALSE and FontName gets set to a zero length string.
FUNCTION WSGetPoint (WS:WSHandle; VAR ThePoint:Fixed):Boolean;
Returns the current point size in WS.
ThePoint is returned as a fixed fraction.
If there is a selection range and the same point size does not hold true throughout the range, the function returns FALSE and ThePoint gets set to zero.
FUNCTION WSGetStyle (WS:WSHandle; VAR TrueStyle,
AnyStyle:Integer):Boolean;
Returns the current style(s) of WS.
TrueStyle and AnyStyle get set in the following way: the bits set in TrueStyle correspond only to those styles within the selection range that hold true throughout; AnyStyle's bits get set to those styles that appear anywhere within the selection range.
You can always tell the difference between "plain" text and text which has no consistent styles -- AnyStyle will always be zero if the text is "plain."
The function returns TRUE only if TrueStyle and AnyStyle are identical.
FUNCTION WSGetColor (WS:WSHandle; VAR Color:RGBColor):Boolean;
Returns the current text foreground color in WS.
Color is set to the exact RGBColor if the same color appears across the selection range.
If there is a selection range and the same color does not hold true throughout the range, the function returns FALSE and Color gets set to all zeros.
PROCEDURE WSSetJust (WS:WSHandle; Just:Integer);
Sets the text justification for WS. The value passed in Just may be one of four:
0 -- Left justify
1 -- Center justify
2 -- Right justify
3 -- Full justify
This procedure does not redisplay the screen -- you must call WSDisplay or WSBitMapDisplay to update the screen contents.
FUNCTION WSGetJust (WS:WSHandle):Integer;
Returns the current justification of WS.
Cut, Copy, Paste
FUNCTION WSCut (WS:WSHandle):Boolean;
Deletes the selected text in WS.
If no text is selected, WSCut does nothing.
The function returns TRUE if WS needs recalculating as a result of the cut.
FUNCTION WSCopy (WS:WSHandle):WSHandle;
Returns a new WSHandle which is a copy of the selection range of WS.
The resulting WSHandle will require recalculation (WSRebuild) if you intend to display it.
If there is no selection range in WS, WSCopy still returns a WSHandle but it will contain empty text with the default format the same format as the source insertion point.
Use WSCopy instead of WSGetSelText if you wish to retain the formatting information.
FUNCTION WSPaste (srcWS,destWS:WSHandle):Boolean;
Inserts the contents of srcWS into destWS at the insertion point of destWS.
The source WSHandle is not altered.
The function returns TRUE if the resulting "paste" requires destWS to be recalculated prior to its re-display.
Note: You can perform WSPaste as many times as you want even if destWS or srcWS require a "rebuild." Calling WSRebuild is only necessary for display.
PROCEDURE WSToScrap (WS:WSHandle);
Copies the entire text contents of WS to the external scrap.
WS is not altered; it does not have to be rebuilt for this operation to work.
Tyically, WS is the handle returned from a WSCopy that you wish to place in the external scrap.
FUNCTION WSScrapToHandle (ViewRect:Rect; Bounds:LongRect;
Flags:LongInt; Hooks:WSHooksPtr;
Format:FormatPtr):WSHandle;
Creates a new WSHandle using the TEXT contents from the external Scrap, if any.
The parameters are 100% identical to WSNew.
If the Scrap contains no TEXT data, WSScrapToHandle returns NIL.
FUNCTION WSCopyFormat (WS:WSHandle):FormatHandle;
Returns a FormatHandle which contains a format run of the selected text in WS.
If no text is selected (i.e., a "caret"), this function still returns a FormatHandle containing a single format record for that insertion point.
This routine is useful for setting up a format change "undo" (by first copying the formatting before applying changes). It is also useful for style sheet manipulation.
Note that WSCopyFormat returns a newly created handles -- the application must dispose it.
Changes the selection range of WS to the format(s) contained in Fmt. The text is not displayed.
Typically, Fmt is a handle obtained from a previous WSCopyFormat call (above). This function is useful for "undo" operations after a formatting change.
Selection Ranges & Scrolling
PROCEDURE WSGetSelect (WS:WSHandle; VAR bSel,eSel:LongInt);
Returns the current selection range of WS. The bSel and eSel parameters are set to the beginning and ending selection ranges of text (relative to all text, not an individual buffer).
Sets the selection range of WS to bSel through eSel. The values are taken as relative to all text in WS (not relative to an individual buffer).
If Show = TRUE, the new highlighting (or caret) is shown; otherwise no visual effect results.
PROCEDURE WSScroll (WS:WSHandle; h,v:LongInt);
Causes the contents of WS to "scroll", moves the Bounds rect by h, v pixels and re-draws the scrolled area.
The movement for negative numbers is left and/or up; positive numbers are down and/or right.
In effect, the contents of the view rectangle are scrolled.
PROCEDURE WSGetScrollState (WS:WSHandle; VAR h,v:LongInt);
Returns the current "scrolled" state of WS.
H returns the amount the contents are scrolled to the left and V returns the amount the contents are scrolled up. Both numbers are positive.
PROCEDURE WSMove (WS:WSHandle; h,v:Integer);
Moves the entire display contents of WS by h and v pixels.
WS is not re-displayed.
This differs from WSScroll in that both ViewRect and Bounds are moved the same distances. Calling WSDisplay would display the contents at the new location.
FUNCTION WSSetBounds (WS:WSHandle; NewBounds:LongRect):Boolean;
Sets the Bounds rect for WS to NewBounds.
The function returns TRUE if the result forces WS to be rebuilt (in which case call WSDisplay, WSBitMapDisplay, or WSRebuild).
NOTE: WSSetBounds forces the scrolled state to 0,0 -- but does not redraw the contents.
PROCEDURE WSGrow (WS:WSHandle; h,v:Integer);
Expands the ViewRect by h and v pixels.
The right edge of ViewRect expands h pixels and the bottom expands v pixels. The contents are not re-drawn.
PROCEDURE WSGetBounds (WS:WSHandle; VAR r:LongRect);
Returns the exact Bounds area which exactly encloses the visual text.
Note the the resulting LongRect is not necessarily identical to the tBounds field in WS -- WSGetBounds computes the bottommost pixel of the last line and sets r.Bottom accordingly.
This procedure is useful for determining the scrollable size of text.
PROCEDURE WSLine2Rect (WS:WSHandle; VAR R:LongRect; VAR Pix:Integer);
Returns display information about the currently selected line.
The LongRect R gets set to the rectangle which encloses the currently selected line exactly.
Pix gets set to the distance from the left edge of R, in pixels, of where the insertion point lives.
WSLine2Rect is useful for determining whether or not you need to automatically scroll the selected area to view.
PROCEDURE WSChar2Pt (WS:WSHandle; Offset:LongInt;
VAR Pos:tSelectPos);
Initializes a tSelectPos record that corresponds to a character location.
Offset is the position into text (relative to the entire text of WS). Pos gets initialized to the exact line, text buffer, and "caret" position of Offset.
PROCEDURE WSPt2Char (WS:WSHandle; P:Point; VAR Pos:tSelectPos);
Initializes a tSelectPos record that corresponds to a local screen point.
WSPt2Char works exactly the same as WSChar2Pt except it is computed from a point instead of a character offset.
Returns the starting and ending point of a full text word corresponding to a character location.
WSChar2Word works exactly the same as WSChar2Pt except two tSelectPos records are set: tSelectPos "b" is set to the first character of the word and "e" is set to the last character.
PROCEDURE WSPt2Word (WS:WSHandle; P:Point; VAR b,e:tSelectPos);
Returns the starting and ending point of a full text word corresponding to a screen point.
WSPt2Word works exactly the same as WSChar2Word except the two tSelectPos records are computed from a local-coordinate screen point.
Returns the starting and ending point of a paragraph corresponding to a character location.
WSChar2Par works exactly the same as WSChar2Word except the result encompasses a paragraph.
PROCEDURE WSPt2Par (WS:WSHandle; P:Point; VAR b,e:tSelectPos);
Returns the starting and ending point of a paragraph corresponding to a screen point.
WSPt2Par works exactly the same as WSPt2Word except except the result encompasses a paragraph.
I/O Support
FUNCTION WSToHandle (WS:WSHandle):Handle;
Returns a newly created handle which contains a completely de-referenced, contiguous stream of data representing WS. WSToHandle essentially concatenates all the internal memory structures in WS and creates a single memory structure which you can now save to a resource file or some other medium.
The source WSHandle is not altered.
If this routine fails (due to insufficient memory), NIL is returned.
CAUTION: WS supports fantastically large editing structures -- if your WSHandle is potentially very large (e.g., megabytes), you should create some other way of saving and retrieving data structures to avoid an out-of-memory situation.
FUNCTION HandleToWS (H:Handle):WSHandle;
Reverses the process from WSToHandle. The function returns a newly created WSHandle.
H is the Handle which was previously obtained from WSToHandle. If this function fails (due to insufficient memory), HandleToWS returns NIL.
FUNCTION WSPrint (WS:WSHandle; Position:LongInt; Dest:Rect):LongInt;
Draws the contents of WS beginning at text offset Position for as many lines that will completely fit in Dest. The drawing occurs to the current GrafPort (which is typically a printer port).
The first line in WS which contains offset Position is "pinned" to the top-left of Dest (which is to say Dest is used in place of tBounds). That first line and all subsequent text that completely fits into Dest is drawn relative to the top-left of Dest; text which falls below Dest.Bottom, even by 1 pixel, is not drawn.
Essentially, WSPring ignores the current "scrolled" state and pins itself to a page rectangle.
The function returns the beginning offset of the first text that did not draw (becuase it did not completely fit in Dest); if ALL text from Position to the end of text was drawn, the function returns -1.
Note that to print a whole "document" you would call WSPrint with Position set to zero, Dest set to the printer port's PageRect, then make subsequent calls to WSPrint with Position = function result until the function returns -1.
IV: Advance Techniques
Customizing Text: UserStyles
Every format record (an element in an array defining a text section's font, style, point size, and color) has an optional pointer to a set of procedure pointers:
UserStylesPtr = ^UserStyles;
UserStyles = RECORD
hMeasureText:ProcPtr; { Text widths measurement proc }
hDrawText:ProcPtr; { Text drawing proc }
hFmtDelete:ProcPtr; { About to delete a FormatRec }
hFontInfo:ProcPtr; { Get font info }
END;
Each function contained in this array of routines is described in detail under the section, "Low-Level Hook Routines," -- the first four functions of UserStyles and the low-level hooks are 100% identical except that each routine for a UserStyle is called only for that particular section of text while the low-level hooks are called for all situations.
Any of the fields that are non-NIL are considered procedure pointers and get called at the appropriate time; hence you can pick and choose which items to use by setting the unneeded routines to NIL.
UserStyle Maintenance
FUNCTION WSSetUserStyle (WS:WSHandle; UserProcs:UserStylesPtr; AndMask,OrMask:LongInt:Boolean;
Sets the insertion point (or selection range) to a UserStyles format. In addition to the UserStylesPtr, the text format assumes the characteristics of the font, style, point size, etc. of the current insertion point or selection range.
The UserProcs parameter points to a UserStyles record which is fully explained under "Low Level Hooks" and "User Styles" sections. Elements of UserProcs that are NIL are not called.
AndMask and OrMask can be anything the application chooses; it is placed in the UserSpace field of the FormatRec that gets inserted into WS and works as follows: The value of AndMask gets logically AND'd to UserSpace (either source or destination bit is a zero the result is zero) and the OrMask gets logically OR'd to UserSpace (either source or destination bit is a one the result is one).
The result of WSSetUserStyle is exactly the same as any other text formatting change except the various functions in UserProcs are called for text measurement, display and deletion. The end result is "customized" text styles and formatting.
The function returns TRUE if text requires re-displaying.
Note that if your UserStyles require special data imbedded in the text stream (such as a picture handle) you can accomplish this by immediately calling WSInsertText after WSSetUserStyle. When doing so, the inserted "text" assumes the characteristic of the UserStyle.
FUNCTION WSFindUserStyle (WS:WSHandle; AndMask,OrMask:LongInt;
VAR Position,Count:LongInt; VAR Fmt:FormatRec):Integer;
Returns the relative position into text of a UserStyle, if any.
The search for a UserStyle begins at Position, walks through the format run until it finds a UserStyle whose UserSpace field meets the criteria of AndMask and OrMask, or comes yo the end of the format run, whichever comes first.
For each potential format record containing a UserStyle (UserProcs field of the format record <> NIL), a comparison is made with AndMask and OrMask as follows: UserSpace is first ANDed with AndMask then compared to OrMask; if a match is made with OrMask, WSFindUserStyle returns with that format record and sets Position and Count to the relatitive text position and number of bytes affected by the format record, respectively. Fmt is also initialized to the full FormatRec.
Note that you can "walk through" all UserStyles regardless of their UserSpace contents by setting both AndMask and OrMask to zero -- if the bits in the UserSpace get ANDed with all zeros, the result is zero and thus it will always match with OrMask. You would eventually, of course, receive a function result of -1 once there were no more UserStyle records after Position.
If a UserStyle is found, the function returns the array element of Fmt in the format run array (the first element = 0); if not found, the function returns -1 and the values of Position, Count, and Fmt are uncertain.
FUNCTION WSSetUserSpace (WS:WSHandle; AndMask,
OrMask:LongInt; Only4User:Boolean):Boolean;
Sets the UserSpace field(s) of the format records for the current insertion point or selection range of WS.
AndMask and OrMask set the UserSpace by first ANDing the AndMask then ORing the OrMask. For merely forcing the UserSpace to a new value set AndMask to zero (which will cause the previous UserSpace to clear) and OrMask to the desired value (which would then set UserSpace to the same value in OrMask).
If Only4User = TRUE, only the format records that contain UserStyles (the UserProcs field in the format record <> NIL) are affected; if FALSE, then all format records within the selection range are affected.
If WS merely has an insertion point (beginning selection = ending selection), no changes to UserSpace take effect until the next WSKey or WSInsert.
FUNCTION WSGetUserSpace (WS:WSHandle;
VAR AllSpaces,AnySpaces:LongInt):LongInt;
Returns the values in the UserSpace field(s) of the current selection range of WS.
AllSpaces and AnySpaces get set in the following way: If any bit of the 32-bit UserSpace within the selection range is a "1" and that same bit holds true through the selection range as a "1" gets set in AllSpaces, while if any bit is a "1" within any UserSpace field of the selection range the corresponding bit gets set.
The function itself returns a copy of the first UserSpace of the selection range. Note that AllSpaces, AnySpaces and and function result will all be equal if WS contains an insertion point (no selection range).
WSGetUserSpace is useful if you are using UserStyles and want to treat the UserSpace field as an extension of text styles.
Additional Format Run Support
The following routines are useful for directly manipulating FormatRecs (a WS format run) in ways not covered by the conventional WSSetFont, WSSetStyle, etc.:
FUNCTION WSFindFormatRec (WS:WSHandle; VAR Position,Count:LongInt;
VAR Fmt:FormatRec):Integer;
Finds and returns the first format record in WS corresponding to text position Position.
Upon return, Position gets updated to the exact text position of the format, Count is initialized to the number of bytes of text affected by this format and Fmt is initialized to the FormatRec itself.
The function itself returns the array element number of the format record (first one = 0).
Note that WSFindFormatRec will always return a format record even if Position is beyond the range of text. The last (ending) format record can be known by examining Position + Count -- if Position + Count = length of all text (which is the tLength field in the WS record) the last format record has been given.
WSFindFormatRec is useful for "walking through" the format run of a WSHandle: by initially setting Position to zero, make repetitive calls to WSFindFormatRec, each time adding Count to Position before the next subsequent call and terminating when Position + Count = length of all text.
PROCEDURE WSSetFormatRec (WS:WSHandle; VAR Fmt:FormatRec; Element:Integer);
Replaces the contents of a format record with the contents of Fmt.
The precise format record replaced is given in Element which is an array position of WS's format run. The first element is 0, the second element is 1, and so on.
Note that Element can be obtained for a specific format record from the function result of WSFindFormatRec, above.
WSSetFormatRec is useful for initializing a previously saved WS structure that requires global format changes (such as new UserStyle hooks or changes to fonts that no longer exist in the system).
Forces different fonts and/or point sizes throughout WS by substituting OldFont with NewFont and/or OldSize with NewSize.
WSFixFonts has been mainly provided to fix a situation where certain fonts no longer exist and need to be substituted by another; similarly, certain point sizes may have been unscaled yesterday but removed from the System today causing an older WSHandle to word-wrap incorrectly.
When this procedure is called, WS searches for all format records contain both OldFont and OldSize and, if found, substitutes NewFont and NewSize.
However, if OldFont is an empty string (length zero) it is considered a "wild card" and causes only the point size to be checked; concurrently, if OldSize = 0, it is considered a "wild card" and only OldFont is checked.
Also, if either NewFont or NewSize is zero length or zero, respectively, it is not substituted. Hence you may pass various combinations to affect only fonts, only styles, or both.
Low-Level "Hook" Routines
As mentioned previously, each WSHandle contains a predefined variable, a WSHookPtr. This is a pointer to several low-level procedure pointers in which the application can intercept for purposes of customized text displays, word-wrapping, etc.
A similar set of hooks, UserStyles, can be used as part of a format record itself causing portions of text to be sectioned off and customized.
In short, the application can "tap in" to WS's most basic functions: WS will make a call to the hook addresses at the appropriate moment, giving the application a change to inspect and/or change the outcome.
The variable WSHooksPtr is predefined as follows:
WSHooksPtr = ^WSHooks;
WSHooks = RECORD
hMeasureText:ProcPtr; { Text widths measurement proc }
hDrawText:ProcPtr; { Text drawing proc }
hFmtDelete:ProcPtr; { About to delete a FormatRec }
hFontInfo:ProcPtr; { Get FontInfo }
hWordBreak:ProcPtr; { Need word break point }
hTabWidth:ProcPtr; { Return width of TAB }
hTabDraw:ProcPtr; { Tab is "drawn" }
hMaxWidth:ProcPtr; { Return maximum line width }
hPreCalc:ProcPtr; { Prepare for line calculation }
hPostCalc:ProcPtr; { Finish line calculation }
hDoneCalc:ProcPtr; { WS thinks it is done with calc.}
hSmartScroll:ProcPtr; { Needs to scroll for CR or backspace}
hPt2Line:ProcPtr; { Return a line containing a point}
hSelectRgn:ProcPtr; { Return a selection region }
hGetBuf:ProcPtr; { Get a text buffer }
hNewBuf:ProcPtr; { Create a new text buffer }
hDeleteBuf:ProcPtr; { Delete a buffer }
hPreDraw:ProcPtr; { Called before drawing a line }
hPostDraw:ProcPtr; { Has just drawn proc }
hrsvd1:ProcPtr; { - reserved - }
hrsvd2:ProcPtr; { - reserved - }
hrsvd3:ProcPtr; { - reserved - }
hrsvd4:ProcPtr; { - reserved - }
END;
If any of the above set of procedure pointers are non-NIL the routine is called at the appropriate moment. The basic idea is to allow an external application intercept the core routines (or completely replace them) to obtain customize objects and display.
To do so, place a pointer to a routine in the appropriate WSHooks field(s), set the hook fields you do not need to use to NIL and place a pointer to the WSHooks record into the tProcs field of the WSHandle you wish to affect.
The same is true for UserStyles except the pointer to the hooks record is passed via WSSetUserStyle.
The following is a description of each hook function:
hMeasureText. Called whenever WS needs to measure the text width of one or more characters. It is taken as:
FUNCTION hMeasureText (WS:WSHandle; VAR Fmt:FormatRec; Txt:Ptr; Count, Slop:Integer; Widths:Ptr):Boolean;
WS is the current WSHandle containing the text to be measured.
Txt is a pointer to the text and Count is the number of bytes to be measured.
Fmt is the current FormatRec of the text's style attributes (Font, style, etc.). Note that the current Font, style, and point size will also be set in the current GrafPort upon entry.
The Slop parameter is the amount of distance to expand the text (such as full justification), in pixels. Note that this value will be zero if the text is not fully justified.
The Widths parameter is a pointer which your application must fill with consecutive integer character positions, in pixels. The first integer is always the position of the zeroth character and should always be zero; the second integer must be the relative pixel position of the next character, and so on.
The result placed in Widths is 100% identical to Quickdraw's MeasureText result (or Script Manager's MeasureJust result) so consult Inside Macintosh for more details.
The hMeasureText function will never pass text which crosses multiple format boundaries; it will also never pass text containing more than one control character. Rather, WS partitions such portions of text and makes multiple hMeasureText calls. In any case, the current Font, Style, point size and color are set in the current GrafPort prior entering your function.
If the function returns TRUE then WS uses the information in Widths; if FALSE, WS ignores the values in Widths and calculates the text width using its own procedure.
hDrawText. Called before WS draws any text. It is taken in the form of:
FUNCTION hDrawText (WS:WSHandle; Txt:Ptr; VAR Fmt:FormatRec; Count,Slop,Ascent,Descent:Integer):Boolean;
WS is the WSHandle being displayed. Txt points to the text to be drawn while Fmt is the current font, text face, point size and color.
Upon entry, the appropriate text format is set in the current GrafPort; the exact pen position is also pre-set to the location to begin drawing.
Count and Slop are the byte count and extra distance to be made up for full justification, respectively.
Ascent and Descent define the total height of the current line -- Ascent is the distance above the current vertical pen position while Descent is the distance below the vertical pen. Hence, currentPen.V-Ascent = text line's "top" and currentPen.V+Descent = current text line's "bottom."
If the application uses hDrawText, it must update the GrafPort's pen position.
If TRUE is returned as the function result, WS assumes the text has been drawn; for FALSE, WS goes ahead and draws the text in the standard way.
NOTE: THE CURRENT GRAFPORT DURING THE EXECUTION OF HDRAWTEXT IS NOT NECESARILY THE GRAFPORT YOU HAD SET BEFORE CALLING WS ROUTINES -- IT IS OFTEN TO AN OFFSCREEN BITMAP.
hFmtDelete. Called prior to a FormatRec (format run element). It is taken in the form of:
WS is the WSHandle containing the text to be deleted. A FormatRec is deleted whenever it is no longer needed due to text deletion. This situation can occur not only from a "cut" operation but also a backspace.
Element is the array element of the FormatRec in question, while Fmt is the FormatRec itself.
The main usage for hFmtDelete is to purge any special structures you might have created for customized "text" (such as picture data).
NOTE: You must never actually delete the FormatRec -- hFmtDelete merely lets you examine the FormatRec and perform any cleanup actions that might be needed.
Warning: You may not re-enter any WS procedure and function during this call.
hFontInfo. Called to get the current Font's height (ascent, descent, and leading values). It is taken in the form of:
PROCEDURE hFontInfo (WS:WSHandle; VAR Fmt:FormatRec; Position:LongInt; VAR fInfo:FontInfo);
WS is the current WSHandle.
Fmt is the precise Font, style, and point size of the text in question; note that this font, style and size is also set in the current GrafPort upon entry.
Position is the absolute offset into text that is being measured (not relative to the current TextBlock).
Prior to entry, WS makes the standard GetFontInfo call to Quickdraw initializing the fInfo parameter; user of this hook may change its values (such as changing the font leading or height).
hWordBreak. Called after a word did not successfully fit on the end of a line. This function is provided as a means for the application to perform hyphenation or other such word breaking. It is taken in the form of:
FUNCTION hWordBreak (WS:WSHandle; Txt,Widths:Ptr; Count,
RemWidth:Integer):Integer;
WS is the WSHandle containing the line being calculated.
Txt is a pointer to the first character of the word that does not fit on the line, while Count is the number of bytes that comprise the word. The "word" will always consist of non-breaking characters and will contain no spaces or control characters.
Widths is a pointer to an array of integers containing precise character widths for each character beginning with the first character of Txt. (Note: this is not the same as the result from MeasureText -- each integer in this table corresponds to exact character widths, including kerning, as opposed to accumulated character positions).
The RemWidth parameter contains the maximum amount of space, in pixels, remaining in the line. The idea is for the application to decide if there is a way to hyphenate the word and make it fit, including the width of the hyphen character.
The function must return an offset of where to break the word; note that a result of ZERO implies that the word should not be broken but merely "wrap" to the next line; any other number will cause the word to break and a hyphenation symbol drawn (the hyphenation symbol used is contained in the Hyphen field of the Globals record -- see Global Parameters).
hTabWidth. Called to get the "width" of a TAB character. The function is called to obtain the amount of distance, in pixels, that should be added to the current text width position.
For example, when WS is measuring text widths, a TAB character is typically computed dynamically depending on the previous character's pixel position.
The function is taken in the form of:
FUNCTION hTabWidth (WS:WSHandle; Txt,Widths:Ptr; Count,
Width:Integer):Integer;
WS is the WSHandle containing the text with a TAB character.
Txt is a pointer to the TAB character in the text and the bytes that follow the TAB. Thus it is possible to compute, say, a decimal or right-justified TAB by examining the adjacent characters.
The Count parameter is the remaining bytes of text either for the current line or the current text buffer; in either case, there will always be enough characters to compute a non-left justified TAB.
Widths is a pointer to an array of integers in which each entry contains the consecutive character widths for each character in Txt; the 0th entry is the width of the first character, the next entry is the width of the second character, and so on. Note that this is not the same as the width table from MeasureText -- the result of MeasureText contains consecutive character positions, while Widths, in this function, contain consecutive widths. Each entry in Widths is guaranteed to be precise according to the text's multiple fonts, styles, and point size.
The Width parameter contains the sum total text width of the text before the TAB character. This value will always be the aggregate character widths from the beginning of a text line up to, but not including, the TAB character. Note that if this is being called during display of text, the Width parameter contains the current pen position minus the starting pen position of the current line.
The function should return the wanted width the of TAB character. However, a negative result causes WS to use the default tab spacing.
WARNING: THE POINTER TO TEXT IS NOT NECESSARILY LOCKED FROM RELOCATING IN MEMORY -- IF YOU DO ANYTHING THAT MIGHT COMPACT THE HEAP THE POINTER TO TEXT WILL BECOME INVALID. THE CHARACTER WIDTHS ARE GIVEN TO YOU DURING THE EXECUTION OF HTABWIDTH SO YOU NORMALLY DON'T HAVE TO MAKE ANY CALLS THAT WILL LOAD RESOURCES (e.g., TextFont, TextWidth, etc.).
hTabDraw. Called right after a TAB character is positioned on the screen. The hTabDraw hook is useful for drawing "leaders." It is taken in the form of:
NewPen is the exact pen position, in local co-ordinates, that the next text drawing will take place after a TAB character (the actual "width" between the end of the last text and the pen position had been previously been obtained from hTabWidth, above). The ending pen position of the previously drawn text is the pen position of the current GrafPort.
In other words, the total distance between the end of the last text and the current TAB mark is NewPen.H minus current GrafPort's horizontal pen position.
Ascent and Descent are the distances above and below the current vertical pen position, respectively.
hMaxWidth. Called to obtain the maximum width for a given line of text. This is always used to determine word-wrapping when a line built and is called first before taking any further line calculation (text measurement) actions. It is taken in the form of:
FUNCTION hMaxWidth (WS:WSHandle; VAR TBuf:TextBlock; Position:Integer):Integer;
WS is the WSHandle containing the line to be computed.
TBuf is a TextBlock record containing the text and line array for the line.
Position is the array element in the line array for the line about to be calculated (the first element is zero).
The function must return the maximum width of the line, in pixels. However, a result of ZERO causes WS to use the default maximum (which is the width of the tBounds area of WS).
The hMaxWidth function is called before hPreCalc, below; it can also be called on any other occassion requiring the maximum distance a given line can be.
hPreCalc. Called just before text measurement for line calculation. The purpose of hPreCalc is to allow the application to interrogate the line's starting structure before calculation begins and making any necessary changes for customized display. The function is taken in the form of:
FUNCTION hPreCalc (WS:WSHandle; VAR TBuf:TextBlock; Position:Integer;
VAR Line:LineRec):Boolean;
WS is the WSHandle containing the line about to be calculated.
TBuf is a TextBlock record containing the text and line array for the line.
Position is the array element in the line array for the line about to be calculated (the first element is zero).
The Line parameter contains the initial values for the line to be calculated; its fields are initialized exactly the same as hMeasureText, above.
Note that the application can change any of the values of Line (or even Offset) to get the desired result; WS will use whatever exists in Line after this function returns.
If the function result is TRUE, WS continues and calculates the line (computing text widths, calling hMeasureText, etc.); if the result is FALSE, WS assumes the application did its own calculation and thus stores Line into the line array as-is.
hPostCalc. Called after a line is completely calculated. The purpose of this function is to let the application make any additional changes to the line entry before it is placed into the line array. It is taken in the form of:
FUNCTION hPostCalc (WS:WSHandle; VAR TBuf:TextBlock; Position:Integer;
VAR Line:LineRec):Boolean;
The parameters and their meanings are 100% identical to hPreCalc.
A function result of TRUE tells WS to "accept" this line and place it into the line array; a result of FALSE is taken as a "rejection," in which case the line is re-calculated (beginning with hMaxWidth and hPreCalc).
hDoneCalc. Called when WS thinks it can quit calculating lines.
The function is taken in the form of:
FUNCTION hDoneCalc (WS:WSHandle; VAR TBuf:TextBlock;
VAR Position:Integer; VAR Line:LineRec):Boolean;
WS is the current WSHandle; TBuf is the current TextBlock record containing the line array.
The Position value is the array element of the line which WS thinks does not need recalculating.
The Line parameter contains the line record WS thinks is not necessary to recalculate. Note that application can change fields as needed.
This function is called whenever WS has only recalculated a portion of the line array but not all, considering that the subsequent lines do not change lengths or word-wrapping (but may change vertical positions) so no further calculation "crunch" is necessary under normal circumstances.
If the function returns TRUE, then the application "agrees" with WS that lines need no further calculation; a result of FALSE tells WS to continue calculating anyway.
If WS does continue calculation (by receiving a FALSE result) it will pick up the next line according to the values in Position and Line -- thus you can force it to continue calculating somewhere else other than the line originally passed in the function.
A typical usage of hDoneCalc is for word-wrapping within "columns" -- while WS assumes a single rectangle for line calculation, it may be required to force new measurements for wrapping to some other area.
hSmartScroll -- Called whenever WS wants to scroll lines up or down on the screen to create a fast response to a RETURN key or backspacing a RETURN character.
Whenever WS detects a situation where lines simply shift up or down, and no new word-wrapping is required, it speeds up the process by merely scrolling the appropriate area of the screen and re-drawing the affected area(s).
The function is called before doing this action. It is taken in the form of:
FUNCTION hSmartScroll (WS:WSHandle; VAR TopLine:LineRec;
VAR Amount:Integer; VAR Box:Rect; Upd:RgnHandle):Boolean;
WS is the WSHandle involved.
TopLine is a copy of the first line affected (this line and all subsequent lines will "scroll").
Amount is the distance it will scroll, in pixels. Negative values scroll UP and positive values scroll down. Note that the application can change this value if necessary.
The Box parameter defines the area of the screen to be scrolled (in which a ScrollRect will be performed). Note that the application can change this rectangle if necessary.
If the application does its own scrolling it should set Upd to the area to update the screen (which is identical to the RgnHandle passed in ScrollRect).
If the function returns TRUE, WS does no scrolling but does update the screen clipped to the Upd RgnHandle; if FALSE is passed, WS goes ahead with the standard scrolling.
hPt2Line. Called to find a line array entry containing a specific point. This function is always called in response to a WSClick (and subsequent mouse tracking) to locate which line the mouse is clicked on. It is taken in the form of:
FUNCTION hPt2Line (WS:WSHandle; P:Point;
VAR TBPosition,LinePosition:Integer):Boolean;
WS is the WSHandle involved.
P contains the point, in local co-ordinates from which to find the line that contains it.
TBPosition and LinePosition should return with the TextBlock and line array elements, respectively (the lowest element = 0).
If the function returns TRUE, WS uses the information in TBPosition and LinePosition to continue processing the mouse-click; if FALSE is the result, WS searches for the line itself with the default routine(s).
hSelectRgn. Called to obtain the area of the screen to be highlighted (inverted). It is taken in the form of:
FUNCTION hSelectRgn (WS:WSHandle; VAR bSel,eSel:tSelectPos, Sel:RgnHandle):Boolean;
WS is the WSHandle involved
The bSel and eSel define the areas to be inverted; both are tSelectPos records which contain the relative text, line, and "caret" positions if a selection range. Note that these are not necessarily the entire selection range of WS -- in mouse tracking, for instance, they will involve small section of text.
If a selection region is indeed determined, the application should fill Sel with the appropriate shape (a group of rectangles, for instance).
If the function returns TRUE, WS inverts the region, otherwise it creates in own selection region in the standard way.
hGetBuf. Called to obtain a text buffer. This hook is typically used for memory management and/or disk buffering of text. It is always called after locating a specific TextBlock in the text buffer array but before using any of its contents. It is taken in the form of:
FUNCTION hGetBuf (WS:WSHandle; Position:Integer;
VAR TBuf:TextBlock):Boolean;
WS is the WSHandle containing the text buffer.
Position is the array element of the TextBlock (first element = 0);
TBuf is the TextBlock record that WS wants to use.
This procedure is useful for, say, reading text from the disk that has been purged from memory. The application must set the function to TRUE if it made any changes to TBuf.
hNewBuf. Called to obtain a new text buffer. It is taken in the form of:
FUNCTION hNewBuf (WS:WSHandle; VAR TBuf:TextBlock):Boolean;
WS is the WSHandle in which the new text buffer will be assigned to.
TBuf is a TextBlock record to be initialized. Upon entry, the TBBegin, TBEnd, and TBHandle fields are initialized (TBHandle contains a handle of text). All other fields are set to zero.
If the application creates the remaining data structures (TBCTL, TBLines) it must pass TRUE in the function result; a return of FALSE causes WS to go ahead and create the rest of TBuf.
hDeleteBuf. Called before deleting a text buffer. It is taken in the form of:
FUNCTION hDeleteBuf (WS:WSHandle; VAR TBuf:TextBlock):Boolean;
WS is the WSHandle containing this text buffer.
TBuf is the TextBlock to be deleted. Unlike hFmtDelete for FormatRec elements, hDeleteBuf expects the application to actually dispose TBuf's memory structures. The application is to only delete the memory structures in TBuf -- not the entry itself in the TextBlock array.
If the function returns TRUE, WS assumes the memory structures in TBuf were disposed and deletes the entry from the TextBlockArray; otherwise it goes ahead and disposes the memory first before the deletion.
Note, however, that if you set any of the memory structures in TBuf to NIL (TBLines, TBHandle, or TBCTL) and pass FALSE for the function result, WS won't try to dispose the NIL handles so this is another way to perform "deletion."
hPreDraw. Called before displaying a line. It is taken as:
PROCEDURE hPreDraw (WS:WSHandle; VAR Line:LineRec);
This particular routine allows the application to examine the contents of a line record just before it is drawn and take appropriate action. A typical example of hPreDraw would be to set some specific justification for a particular paragraph.
hPostDraw. Called after WS is completely done drawing text. The text drawn could have been a single character (such as a response to WSKey) or multiple lines of text; in any case, hPostDraw gives the application a chance to add any misc. items to the screen (such as "ruler" settings, page break lines, etc.). It also allows drawing special global elements that could have been erased as a result of the drawing. It is taken in the form of:
PROCEDURE hPostDraw (WS:WSHandle);
The only parameter is WS which is the WSHandle just drawn.
WARNING: YOU MAY NOT ENTER ANY WS ROUTINES WHILE EXECUTING ANY OF THE ABOVE HOOKS. YOU MAY, HOWEVER, ENTER OTHER LOW-LEVEL HOOKS.
Tips & Hints on using Low-Level Hooks
1. Text editing will slow down dramatically if you have long, data-crunching routines for some of the hooks. The more important speed-critical hooks are hMeasureText, hDrawText, hTabWidth, and hWordBreak. Of these four, the two most critical are hMeasureText and hWordBreak since they are called many times during the course of large text calculations. You should optimize your code as much as possible when patching into any of these.
2. You may never re-enter any main WS routine while executing a hook. The result will be a major crash. The hooks have been carefully designed to provide most of the information you will need to execute even the most unusual customization.
3. It is OK to set the ClipRgn of the current GrafPort while a hook is executing. WS will restore the original ClipRgn before its final return to the application from the main routine it entered.
4. You cannot assume the current GrafPort is the same one you had set when entering a WS procedure or function. Drawing often occurs to an offscreen bitmap (or PixMap if color).
5. If you have both a UserStyle and a WSHooks element for the same procedure (for instance, both UserStyle and WSHooks have an hMeasureText), WS gives priority to the UserStyle and will call it and not the WSHook whenever that conflict exists.
6. For UserStyles, it is NOT a good idea to imbed memory structures (such as picture handles) into text -- WS might delete a piece of it before you get a chance to dispose of the structure; it can also be erroneously considered a piece of 2-byte script by Script Manager. In any event, it's a bad move and you're asking for trouble. Instead, insert some unique reference number (preferably in UserSpace field) that can index the data somewhere else in your code.
7. UserStyles work just like any other style change -- that means they won't take effect until that style's range encloses at least one byte. If necessary, you should insert a dummy character (preferably a non-control character) after a WSSetUserStyle if you want the "style" to take effect immediately. You can also avoid drawing the dummy character by use of the hDrawText UserStyle hook.
8. If you save a WSHandle to disk or some other resource, remember that your UserStyle hooks will no longer by valid when the file is re-opened later on (the ProcPtr values will point to the old program locations). To avoid this problem, you "walk through" all the UserStyles (using WSFindUserStyle) and replace the hooks before doing anything else with the WSHandle. WSFindUserStyle is guaranteed to work even with "bad" UserStyle hooks since nowhere in that routine do any hooks get called.
